This document is a reference for scripting the ACE application. It is not an introduction or guide to AppleScript.
Scripting allows an application to be used in powerful new ways - customised for the individual user, or oriented around specific tasks. See the section 'Script Ideas' below for examples related to ACE.
Scripting also allows you to work with other scriptable applications. For our purposes, the Finder is the most useful application to script.
Learning AppleScript
Even if you've never done any programming before, you can learn AppleScript just by looking at scripts that other people have written. Use the "Script Editor" application to open some of the scripts in the "Scripts" folder.
The Open Scripting Architecture and AppleScript
The Open Scripting Architecture (hereafter OSA) is the name given to the framework used to build scriptable applications. An application that supports the OSA is said to be scriptable. This scriptability is language independent.
AppleScript is a scripting language, and is only one possible language that can be used to script a scriptable application. Currently, there are two other OSA compliant languages: Frontier and MacPearl.
All the scripts provided with ACE, and all the examples given in this document are written in AppleScript. However, there is nothing that prevents ACE! from being scripted with any other OSA compliant language.
Script usage
Scripts can be used in two ways: as applications ('applets' or 'droplets') launched from the Finder, or from within ACE! via the script menu. The former is useful for drag-and-drop operations, or for scripts that perform a task within ACE! and then quit. The latter is more suited to scripts that are only used in ACE. Note that there is no reason a script cannot be designed for both situations
Example: The "Backup and Open…" and "Open Folder Contents…" scripts are droplets that can have files dropped onto them in the Finder. They can also be run from the "Script" menu within ACE!
Creating a script
To create a script, you will need to be familiar with the syntax of the scripting language you are going to use, and you will need to know ACE's particular scripting commands. You will also need a script editor application.
For most users, the AppleScript language is most suitable, since it is easy to learn and is installed as a standard part of the MacOS. Apple's script editing application (called, "Script Editor") can be installed from the MacOS CD if it is not present.
Once you have written and tested your script, enter a description in the description field of the script window (ACE! will truncate this description to 255 characters in length if it is longer). The user can view this description in ACE! by holding down the option key while selecting a script from the script menu. For applets and droplets, this text also appears in the Finder balloon-help.
Installing scripts
To make a script appear in ACE's script menu, simply drop the script in the "Script" folder. If ACE is open, you will need to quit and re-open it. The script must be a compiled script, an 'applet', or a 'droplet'. You can put folders and other files in the "Scripts" folder, but they will not be recognised, and their contents will not appear in the script menu.
Scripts that work with a particular module can be embedded in that module. A module can have multiple scripts embedded in it. These scripts appear at the bottom of the script menu only when the module is the currently selected module. Obviously, installing an 'applet' or 'droplet' in this way is meaningless.
To install an embedded module script, you must first compile and save your script. Open the script with ResEdit and copy the 'scpt' id 128 resource. Open the module with ResEdit, and paste. If there is already a 'scpt' id 128 resource, click on the Unique Id button. The first script in a module should have an id of 128, and subsequent scripts should have id 129, 130 etc.
You should also copy the description text from your script: Copy the 'TEXT' id 1128 resource and paste it into the module. If a module contains multiple scripts, then each corresponding description text should have an id equal to the 'scpt' id, plus 1000.
Example: The description for 'scpt' id 128 should be in 'TEXT' id 1128, the description for 'scpt' id 129 should be in 'TEXT' id 1129 etc.
You must also give each 'scpt' resource a name (Use ResEdit's Get Resource Info command).
Note: Every script that appears in the script menu must have a unique name.
To help the user determine what a script will affect, the following naming convention is recommended: If a script acts on the front window, the word 'this' will appear in the script name.
Example (Bard's Tale): "Heal this character"
If a script acts on all open windows, the word 'all' is used.
Example: "Roster All Windows"
Assigning command keys to scripts
A script that appears in the Script menu can have a command key assigned to it. To do this, open the script with ResEdit and create a 'STR#' resource with id 1000. In this resource, create one string, and enter the character to be used with the command key. The "Next Window" script has had the command key ']' assigned to it in this way.
You can also add command keys to embedded scripts. Create a 'STR#' id 1000 resource, and use a 'STR#' index that is equal to the id of the 'scpt' resource, minus 127. So a command key for the first embedded script is in 'STR#' id 1000, index of 1, a command key for the second embedded script is in 'STR#' id 1000, index 2 etc.
Note: Don't use a command key that is already used by the ACE! application, or by a script in the script folder. It's ok to use the same command key for scripts that are embedded in different modules, as only one module can be active at any time.
Script Dictionary
You can use the Open Dictionary… command in the File menu of the Script Editor to view the AppleScript commands (plain type) and objects (italics) that ACE! supports.
Note: The Print command takes a list of windows as it's parameter, not a list of files.
Note: The optional 'to' parameter of the save command is specified by a path. E.g. "Macintosh HD:Documents:New File". This is the equivalent of the user choosing Save A Copy As… from the File menu, and saving the save game with the name "New File" in the "Documents" folder of the hard disc "Macintosh HD". If the file already exists, it will be replaced without warning!
With AppleScript 1.3.2 (included with MacOS 8.5 and 8.5.1), the Script Editor will not show the required suite of commands. For reference, they are:
open: Open the specified object(s)
open alias -- list of objects to open
print: Print the specified object(s)
print alias -- list of objects to print
quit: Quit application
quit
run: Sent to an application when it is double-clicked
run
The other command suite will display correctly.
Scripting Tabbed Windows
Tabbed windows are scripted in exactly the same way as a normal (non-tabbed) window. The control referred to in the script does not need to be on the screen. It is not possible to select window panes via a script.
Scripting Lists
Lists and their contents can be scripted. The elements and properties associated with lists are defined in the ACE! Script Dictionary. Note that:
1. The items in a list are called 'cells' (item is a reserved word in AppleScript). However, the word item should be used in all documentation.
2. The name parameter of a list is singular, i.e. "item" or "spell" instead of "items" or "spells". If you want to present the name of the list to the user, make it plural by adding an 's'.
3. To determine the number of cells in a list, use the count command. If the result is 0, there are no cells in the list.
The 'data' property of a cell determines what the cell "is". It is a list of integers (at least one, and no more than eight). Each integer in the list corresponds to a control in the item editing dialog.
Example: In Bard's Tale, an inventory item consists of two pieces of data - an equipped status and the item type.
You can determine how many integers are in a list by counting the items.
Example: get count of items in theData
You therefore edit a list item by getting it's data, changing one or more items in the data and then setting the data again.
You can determine the currently selected dialog item (list or edit text item) by getting the focus property of a window. To determine if the item with focus is a list or an edit text item, count the number of controls, and if the focus item is greater, the focus is on a list:
set theCount to count controls of front window
set theFocus to focus of front window
if ((theFocus - theCount) > 0) then
-- The focus is on a list, and it's index is (theFocus - theCount)
set theList to (theFocus - theCount)
else
-- The focus is not on a list
set theList to 0
end if
The currently selected item in a list can be determined by the selection property of a list. Note that is it possible for a list to have no selection - when it is empty, or when no item is selected.
Script Ideas
To help you get started with scripting, here are some ideas:
• You can script ACE so that it works without any user interaction at all. Obviously, this is only useful when you know in advance exactly what you want ACE to do!
The following script creates a 'droplet' - any Marathon save game that is dropped onto it from the Finder will have the shields and oxygen set to a very large value. Note that the script automatically saves and quits.
Note: This script will actually attempt to use any file dropped onto it. You might want to add some checks to see if these files are actually Marathon files.
Note: Scripts that open files must check to see if there are any windows already open in ACE. If there are, we must assume that windows belong to a different module, and abort execution of the script (a script can get the name of the current module, but the current module can only be set by opening a file).
--
on open theList
tell application "ACE!"
activate
repeat with theFile in theList
open theFile
end repeat
set theCount to count of windows
if (theCount ≠ 0) then
set theLoop to 1
repeat with theLoop from 1 to theCount
tell window (theLoop)
set value of control 1 to 32000
set value of control 2 to 32000
end tell
save window (theLoop)
end repeat
end if
quit
end tell
end open
• This script opens a specified group of files
--
tell application "ACE!"
activate
open {alias "Wipooh:Games:Bard's Tale:Characters:Everon", ¬
alias "Wipooh:Games:Bard's Tale:Characters:Illius", ¬
alias "Wipooh:Games:Bard's Tale:Characters:Terwin"}
end tell
Of course, you will have to enter your own file paths in the above script.
Hint: To see the file path for any file, select the file in the Finder and choose Get Info from the File menu. The file path is listed beside the where: field.
Hint: By modifying the "Open Folder Contents" script, you could make a script that automatically opens the contents of a specific folder.
Note: The ¬ character is entered by holding down the option key while pressing return in the Script Editor. It allows you to split a command over more than one line.
You could also add some code to the above script to automatically position the windows.
• A much more general 'max out' script could be written that works for all modules. For each control, get the maximum value and then set the control value to this number. For very large maximum values, it would probably be prudent to set the control value to slightly less than the maximum.
